package com.liuqi.openai.chain;

import com.liuqi.openai.chain.result.ChainResult;
import java.util.Map;

/**
 * openai 交互链
 *
 * @author liuqi
 * @date 2025/7/20
 **/
public interface OpenAiChain<Input> {

    /**
     * 调用大模型生成结果. 非流式响应
     *
     * @param input 输入内容
     * @return
     * @throws OpenAiChainException
     */
    ChainResult execute(Input input) throws OpenAiChainException;

    /**
     * 调用大模型生成结果. 流式响应
     *
     * @param input 输入内容
     * @param handler 接收流式响应
     * @return
     * @throws OpenAiChainException
     */
    ChainResult execute(Input input, ChainStreamingHandler handler) throws OpenAiChainException;

    /**
     * 为当前对话注入变量，在这一次对话时，这些变量应当是一直存在.
     * 当对话结束后，这些变量需要立刻消耗
     *
     * 在外部工具调用的时候非常有用，例如每次对话把Cookie设置进去
     *
     * @param variables
     */
    OpenAiChain<Input> injectCurrentChatVariables(Map<String, String> variables);

    /**
     * 终止当前于Ai模型的对话
     * 停止Ai模型输出结果
     */
    void stop();

}
